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This module contains the definitions for the control blocks 
that are used in communications between DEBUG and the 

ADA multi-tasking run-time system. These same definitions will be 
extended for use in communication with the PPA multi-tasking 
system and other run-time systems, at a future time. 
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EXTERNAL CONTROL BLOCK 


An “External Control Block’’ is a data structure that can be used 
when DEBUG needs te call a routine that is not Linked in as 
part of the DEBUG image. 


For example, DEBUG will have commands to support ADA wus Sy-teet 190 
However, DEBUG has no knowledge of the workings of the ADA mutli- 
system and the data structures that describe tasks. Instead, DEBUG 
will call ? routine in the ADA multitasking system in the course 

of processing SHOW TASK, SET TASK, or any other command that requires 
knowledge about tasks. 


There will be a single ay ty ADASDBGEXT, in the ADA ge ah 
system which is called by DEBUG. fhe External Control Block is the only 
parameter. Similarly, other multitasking run-time systems will have a 
single entry point, of the form <facility>SOBGEXT, with the entry point 
taking an External Control Block as its single parameter. In general, 
the External Control Block can be used as a means of communication with 
run-time systems that are not part of DEBUG. for example, in debugging 
the Language SCAN we may want to allow the user to set rate nts on 
events such as a SCAN pattern-match. The External Control Block will 

be ~~ data structure that we use to communicate with the SCAN run-time 
system. 


The DBGEXTSV_FACILITY_ID field identifies which run-time system is being 
called. The VAX/VMS Facility code is used. Thus, it is assumed that 


| 
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Since there are several functions we want each run-time system 
to perform for us, there is a DBGEXTSW_FUNCTION_CODE field 
which specifies which function is to be performed. 


ALL functions return a status code in the DBGEXTSL_STATUS field. 
For all functions, there is a DBGEXTSL_FLAGS field which can be used 
- o Ottvector of flags. The exact use of these flags depends on 

e function. 


33 
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The use of the remaining fields of the data structure Gepgnds upon 
the “FACILITY_ID" field and upon the “‘FUNCTION_CODE"’ field. 


NOTE: DEBUG makes these calls with ASTs disabled. It is required 
that the run-time code not reenable ASTs during its execution. 


ho 
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The sol teving illustrates the header of an External Control Block. 
The fields of an External Control Block are then illustrated 
for the case where the “FACILITY_ID" is “ADA”. 


The following header is common to all External Control Blocks: 


1 goa SS oe oh om oe Se SSBB T TSM OaTeon DEBUT Baan Z ES SESernanernwaaneoraana} 

191 0 iunused iv FACILITY, ID { DOBGEXTSw_ FUNCTION CODE H 

198 1 : DBGEXTSL STATUS : 

1 Gveeecenseseeosesccesooessesoeseceesessosesce eeeeeacoee + 

199 2 i (some flags unused) DBGEXTSL FLAGS : 

10 <> 7 reserved. for future use ! 
01 08 Geoeeceeesoeoooosesooesoosooooossooescosesosocooooeso + 
0109 
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; 119 ' The @ fot toning iUhustrates the forsee St — when the FACILITY_ID 
: 11 i fie ‘ADA’’, This control block 

3 118 i ter most functions tsone nay | bert e.g. “GET REGISTERS and SET_REGISTERS 
3 BF ; use a longer control block, displayed later): 

: 1 1 5 ' $e mw ee woe Se eoeanrae SROs anon rrSe seca reoonannaamranasaean $ 

3 118 0 iunused | ‘+ VIFACILITY_ID { DBGEXTSW_FUNCTION_CODE ' 

; 118 a DBGEXTSL_STATUS i 

; 120 i 2 {some flags unused) DBGEXTSL_FLAGS i 

; ' : 3 : reserved for future use : 

>: 0126 ay ee DBGEXTSL_TASK_VALUE 

4 1 5 8 ' ten ane moe oe ee er meroee weeescooesoooe Qaeseeean mores eae } 

3 0 $ 9 5 ‘ DBGEXTSL TASK. NUMBER : 

; 3 : 8 6 ‘unused Ve HOLD! VL STATE. t DBGEXTSU_ SPECIFIED ~fLAGS: 

: 0130 0 oe ae DBGEXTSV_PRIORITY } 

3 01 1 0 ! t¢eroeccece Seow eee eeseeeeeeeeeeeseeeesseerese eecceseseoe + 

3 01 ¢ 0 : 8 : DBGEXTSL_PRINT “ROUTINE ' 

; «6t 0 : Femmeewn enews enwocecososococosoescececesoccooccce + 

; 01 0 : 9 : DBGEXTSL_EVENT_ID H 

; Wis ® : Heme ee en wn en en ween eee ees sosocesoewcococccccccccces + 

; 0136 O : 
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: 0137 ' 

3 13 ! The following hate are Bay = when the ‘FACILITY_I1D" field is 
3 1 ' “ADA and co onc 

: 0140 i DBGEXT “Gel TREGISTERS, 

> 0141 i DBGEXTSK~ =SET=RE REGISTERS, 

: 148 i DBGEXTSK~ 

3 14 ! For all other Soatisns, the smaller block (without the register fields) 
3 144 ' is passed in. 

ONS ; . 
; 149 Pe junused : VFACILITY.ID i _DBGEXTSW_FUNCTION CODE 
; 145 beat i DBGEXTSL_STATUS ; i 
; 3 a i(some flags unused) DBGEXTSL_FLAGS i 
; 91 § 9 we tor reserved for future use ' 
3 1 54 ' $row occ eoee wee ener ewe eee wee See CaM ORE DEMOS eae woe a 
: 0135 0 aS __DBGEXTSL_TASK VALUE i 
: 0137 ; : $ i ~ DBGEXTSL_ TASK NUMBER i 
: 0139 9 ; 6 funused :V_HOLD! V.STATE ! DBGEXTSW_ SPECIFIED FLAGS! 
: o161 i 7? i DBGEXTSV -PRIORITY i 
: oles 0 | 8 i DBGEXTSL “PRINT _ROUT INE i 
; 016s ‘ i 9 i DBGEXTSL “EVENT_1D- i 
; Ole? ‘ i 10 i DBGEXTSL_RO i 
: b160 = a DBGEXT$L_R1 
3 170 : a a + 
: o171 Bet oe: DBGEXTSL_R2 : 
3 0178 eee ee DBGEXTSL_R3 : 
; 173 6 i 14 i DBGEXTSL_R4 i 
; 177 0 | 1s i DBGEXTS$L_RS 3 
: 199 i 1% 3 _DBGEXTSL_R6 
3 1 : Goseeeosrnesraserssesesscesosescoeasessesoresesesrsse + 
; ibs i 47} “DBGEXTSL_R7 
3 1 Ht ; Qeeeesesereraserreussssesrssessacsssesausnesesansess + 
; 183 i 1% 3 DBGEXTSL_R8 .! 
; 185 i 9 i DBGEXTSL_R9 i 
; 139 i 20 } DBGEXTSL_R10 } 
3 1 ' bee more m me ce meme me tomes oOo sen Tees Oe er ee ween eee + 
; 189 im __DBGEXTSL_R11 ; 
: 0190 i Gausesnsenee StenteNtisnnen_eeerlrasminanneeeadintne + 
F 191 Eee ~ DBGEXTSL_AP : 
: 198 i 23} DBGEXTSL_FP ; 
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‘+ 
: CONTROL BLOCK FIELDS 


PEELE FOCERTONEADER_F TELDS = 


DBGEXTSW_FUNCTION_CODE = + we 18. ° 

DBGEXTSV_FACILITY_ID = ° 8. ld, ° 

' reserved = « Oe De Ble 

DBGEXTSL_STATUS =€1, 0, 32, 03, 

DBGEXTSL Fees = ° ° 3¢. ° 
DBGERTSV_ALL = 2, 0. 1. O-RC(WHAT WILL ALL DO?-tbs))% 
DBGEXTSV_FULL = » i, 1, 03,2¢Cexplain FULL -tbs))% 
DBGEXTS$V_PSEUDO_GO C 2. 1, 0), 


POPPI POPIPINININININIPIPIPITPTD 


WWIII NUINININININININ 2 2 OO OO Oo 


S 2. 
! Pseudo-go is set by the run-time system on return to DEBUG to 


! indicate that DEBUG must do a pseudo-GO to accomplish the function. 
! Used only for function SET_ACTIVE (see discussion under SET_ACTIVE). 
DBGEXTSV_NO_HEADER *t 2 3. 1%, 03 

: superenter output of headers on a SHOW_TASK, SHOW STATISTICS, 

! or SHOW _DEADLOCKS. 

! reserved = f 0. 4. 9 0), 

! reserved SE Ge Ge Mo Bes 


TES; 
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FIELD DBGEXTSADA_FIELDS = 
DBGEXTSL_TASK_VALUE 
DBGEXTS$L—TASK-NUMB 
DBGEXTSW~SPECTFIED_F 

DBGERTSV 
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DBGEXTSV_PRIORTT 
' reserve 
DBGEXT$V_STAT 
DBGERTSV_STATE_RUNNING 
DBGEXTSV_STATE_READY 
DBGEXTSV_STATE_SUSPENDED 
V_STATE_TERMINATED 
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Senora} ly. multiple priorities and states are valid as input when calling 
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the 0} HI 
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fields when multi 
Constants for pecex 


TERAL 
DBGEXTSK_MIN_STATE 
TSK"MAX STATE 
$S_STATE 
dB “STATE_RUNN 


GEXTSK_ ING 
DBGEXTSK_ STATES READY 
TATE_ SUSPENDED 
TATE_TERMINATED 


DBGEXTS$K_ 
DBGEXTSK~ 


DBGEXTSS_HOLD 
DBGEXTSK_HOLD 


DBGEXTSS_PRI 


ORITY 
DBGEXTSK~PRIORITY_00 
DBGEXTSK~PRIORITY~01 
DBGEXTSK_PRIORITY~02 
DBGEXTS$K~PRIORITY~0 
DBGEXTSK-PRIORITY04 
DBGEXTSK~PRIORITY~05 
DBGEXTSK_PRIORITY-06 
DBGEXTEK-PRIORITY~0 
DBGEXTSK~PRIORITY~08 
DBGEXTS$K~PRIORITY~09 
DBGEXTSK~PRIORITY~10 

GEXTSK~PRIORITY~11 
DBGEXTSK_PRIORITY~12 
GEXTSK-PRIORITY~1 
DBGEXTSK-PRIORITY~14 
DBGEXTSK~PRIORITY~1 
DBGEXTSK~PRIORITY~1 
DBGEXTSK~PRIORITY~1 
GEXTSK-PRIORITY~1 
DBGEXT$K~PRIORITY~1 
GEXTSK-PRIORITY 
DBGEXTSK~PRIORITY 
DBGEXTSK~PRIORITY 
DBGEXTSK- PRIORITY 
$K"PRIORITY 
S$K"PRIORITY 
$K"PRIORITY 
$K"PRIORITY 
SK-PRIORITY 
1ORITY 
$K"PRIORITY 
SK"PRIORITY 


=O ODNOU’NE WIN - OVOONOu 


oc 
wm 
te = 
Att tt HH 


seepeeepepe ees es 
EAPIPOPINIMININININPIND 


and testin 


run time system but are not valid as output values on return from 
Therefore, the following constants are 
the gyntenss of the ete 
define the — possi 
ities and state 
HOLD are provided for completeness. 


rovided for seauannenee 
BGEXTSV STATE and 

ble values of the respective 
$ are not allowed. 


Z( (superfluous? -tbs))% 


! size of DBGEXTSV_STATE 
! values for OSGEXTSV_STATE 


' size of DBGEXTS$SV_HOLD 
! values for DBGEXTS$SV_HOLD 


' size of DBGEXTSV_PRIORITY 
! values for DBGEXTSV_PRIORITY 
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FRCILITY CODES 


The following are the possible values of the DBGEXTSV_FACILITY_ID field. 
These correspond to the different run-time system we are 
communicating with. 


ADAS aya tee 
PPAS_FACILITY 
SCNS_FACILITY 


'QUES® Z£((-tbs))% 
! Do PPA and SCAN have facility mnemonics and codes? Are the 
! above guesses correct? 
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FUNCTION CODES 


The following are the opera ibie yotyss of the DBGEXTSW 45; hee, a field 
when the contents FACILITY_ID field is ADASFACTLI Ros 
correspond to the A. ons that the ADA run-time end en Tau i sohed to 
pertora. 
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Summary of the defined Function codes 
DBGEXTSK_MIN_FUNCT = 1, ! For CASE bounds 


These are used to obtain and convert task values 
DBGEXTS$K ofVt VALUE _NUM = 1, 


RENLSSSLE 


. ‘ 

4 i 

4 i 

4 i 

4 i 

: i 

: i 

; i 

: i 

: i 

: i 

4 i 

4 i 

; i 

3 : DBGEXTSK~CVT-NUM_VALUE s ¢: 

3 ord DAGEXTSK “NEXT” MASK = 5, 

; bo? 0 ! These are used to ask ADA to a task information 

3 08 4 DBGEXTSK_SHOW_ TASK 

3 0409 0 : DBGEXT$K_ SHOW- STATISTICS = 5, 

3 gery 8 DBGEXTS$K~ SHOW DEADLOCK = 6, 

3 Beig 0 These re. wee we get and set various attributes of one or more tasks 
3 get 8 ' DBGEXTSK Midi * STATE Sf. 

; 15 i DBGEXTSK_GET ACTIVE = 8, 

3 Beis : DBGEXTSK_SET_ACTIVE = 9 

; 1 is DBGEXTSK “SET TERMINATE = 16, : 
; 0418 0 i —- DBGEXT$KSET“HOLD = 11, h 
; 0619 0 ‘ 

:; 0620 0 : Task priorit 

i DBGEXTSK GET. PRIORITY = 1. 

3 § : DBGEXTSK_SET_ PRIORITY = 15, 

3 04 Z : DBGEXTSK-RESTORE_PRIORITY = 14, 

3 be 5 : Task rear aecl 

$ 04 $ : DBGEXTSK_GET_REGISTERS = 15, 

3 Be i DBGEXTSK"SET_REGISTERS = 16, 

; 0629 ' These ore used to conerol definable events 

; 606 ‘ DBGEXTSK_ENABLE EVENT = 17, 

3 1 DBGEXTS$K-DISABLE_EVENT = 18, 

5 § DBGEXTSK_MAX_FUNCT = 18; ! For CASE bounds 
; 5 ie 
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LITERAL 
} A minimum task code is defined for CASE statement bounds. 
DBGEXTSK_MIN_FUNCT = 1, 


CVT_VALUE_NUM takes a task value and converts it to a task number. 

INPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
OUTPUT - The task number is returned in the DBGEXTSL_TASK_NUMBER field. 
} (If the task does not exist, this function returns 

i 
i 


status STS$K_SEVERE).2(( TASK DOES NOT EXIST CODE? -tbs))% 
Z( (VALUE IS ROT LEGAL OR ACCVIO? -tbs))% 


DBGEXTSK_CVT_VALUE_NUM = 1, 

CVT_NUM_VALUE takes a task number and converts it to a task value. 
INPUT - The task number is placed in the DBGEXTSL_TASK_NUMBER field. 
OUTPUT - The task value is returned in the DBGEXTSL_TASK_VALUE field. 
: (If the task does not exist, this function returns 

status STSSK_SEVERE).2((TASK DOES NOT EXIST CODE? -tbs))2% 
DBGEXTSK_CVT_NUM_VALUE = 2, 


NEXT_TASK gives a task value and asks ADA to specify the ‘'next’’ task. 
! The ordering of tasks is up to the ADA run-time system. The only 
! requirement on order is that if we start with any task, and repeatedly 
' ask for the ‘‘next’’ without giving the user program control in between, 
' then we will cycle soreurs all the tasks and return to the task we 
' started with. If selection criteria are imposed, then we will cycle 
! through all tasks which match that criteria. 


i INPUTS - The task value is placed in the DBGEXTSL_TASK_VALUE field. 


'‘ 

' 

' 

' 

' 

' 

' 

' 

' 

‘ 

: If the TASK_VALUE field is zero (implying the NULL task) the 
next task will be the main task of the program. 
' 
' 
‘ 
' 
' 
' 
' 
' 
‘ 
' 
' 
' 


The ALL flag is ignored, ADA will consider it on by default. 


The set of tasks fo cycle through can be restricted b 

impos ing a selection criteria. The PRIORITY, and/or STATE, 
and/or HOLD fields can contain values which a task must matc 
to be part of the set (e.g. SHOW TASK/PRI=3/HOLD/STATE=READY 
When such a restriction is desired, the DBGEXTSV_xxx_SPECIFI 
bits must be set accordingly. If no restriction is desired, 
the _SPECIFIED bits aust e zero. A task must match all the 
critéria which are specified to be part of the set. 


'Z( (Multiple PRI and STATE can be given as these are bit fields -tbs))% 
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about deadlocks within the multitasking system. 


INPUTS - The address of a Rd i routine is given in the field 
DBGEXTSL_PRINT_ROUT 


f the pecker sv FULL bit is set, more detailed information 


s displayed. 
OUTPUT = none, 
DBGEXTSK_ SHOW_DEADLOCK = 6, 


, GET STATE sneuives . got i ‘state’’ and HOLD condition of a task. The 
state’ can READY, SUSPENDED, TERMI 
The state A Ry ore Ohetin ~y oe 


iNPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 


MINATED. 


> 0494 ' 

3 95 } OUTPUT = The ‘‘next’’ task value is returned in DBGEXTSL_TASK_VALUE. 

; DBGEXTSK_NEXT_TASK = 3, 

: 500 ! SHOW_TASK is used to request that ADA display information about a 

: B20) } specified task. 

; 0308 ! INPUTS - The task value is placed in the DBGEXTSL_TASK_VALUE field. 

; 03 5 i The address of a pring routine that ADA is to goths to displa 
; 5 : the information pieced tn in the field DBGEXT RINT_ROUTIN 
; 9307 (see DBGSPRINT "ROUT I E below). 

; 0509 i f the DBGEXTSV_FULL bit is set, more detailed information 

3 peo } s displayed. 

; b2i¢ i QUTPUT = none. 

3061 ‘ 

3 0514 0 DBGEXTSK _SHOW_ TASK 2 4, 

3 Bet? 8 

: ba19 0 ! SHOW_STATISTICS requests that the ADA run-time system display 

3 43 4 0 } statistics about the overall state of the multitasking system. 

: 0520 9 i INPUTS - The address of a opring routine is given in the field 

3 Be 1 8 } DBGEXTSL_PRINT_ROUTINE. 

; «05 j 0 i If the DBGEXTSV_FULL bit is set, more detailed information 

>; 0526 QO ‘ is displayed. 

; 0525 0 ‘ 

s 0 $ 0 ' OUTPUT = none. 

a> Se 0 ! 

$ 0528 O DBGEXTSK_ SHOW _STAT s 3, 

8G 

: 05 : ? SHOW_DEADLOCK requests that the ADA run-time system display information 
; 5 
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OUTPUTS = A code re resent ing the state is returned in thex Z((V_STATE -tbs))% 
DBGEXTSwW_STATE field. 


The DBGEXTSV_HOLD field is also set if the task is on HOLD. 


BGEXTSK_GET_STATE = 7, 


GET_ACTIVE obtains the task value of the active task. 

(The active task is that task in whose context (stack and register set) 
DEBUG is executing, This is contrasted with the ‘visible task’’ -- 

the task whose register set is poaperer ts in_use by DEBUG 

as a default for the purposes of SHOW CALLS, EXAMINE, etc.). 


INPUTS = none 


OUTPUT - The task lue of the active task is returned 
in DBGEXT$L_TASK_VALUE. 


Z(( Can the active task be the null task? -tbs))% 


BGEXTSK_GET_ACTIVE = 8, 


SET_ACTIVE requests the run-time system to switch the active 
task to that given in DBGEXTSL_TASK_VALUE. The ‘‘long form'’ DBG 
control block is used. The rSpretere provided by DEBUG in the control 
block are those of the (currently) active task. The run-time 
system uses these to save the registers of the active task. It 
may also modify this register set, (currently only the PC and PSL). 
When this call returns, DEBUG should use the possibly-modified 
register values as the active register set. If the PSEUDO_GO bit 
is set, DEBUG should then perform the actions of a normal 60, 
except that ASTs are left disabled. This ‘‘pseudo-GO"’ 
will enter special run-time code that will switch-out the 
currently active task, switch-in the requested active task, and 
reinvoke DEBUG in that task. | (A special event code is assigned 
to this “‘reinvoke DEBUG event’’. The reinvokation event signifies 
to DEBUG that certain components of its state are to be 
gotten from values saved from DEBUG's prior incarnation, not those 
at the reinvokation event. One such saved state component is 
the “AST enablement’’ status - whether ASTs were enabled when 
DEBUG was invoked.) 
Despite these gycetion - to the user typing 
DBG> SET TASK/ACTIVE Tl, it appears he has entered a simple command 
immediately followed by a DBG> prompt. 


INPUTS = The task value of the to-become-active task is set 
in DBGEXTSL_TASK_VALUE. 


The registers of the Kcurrons ty? gct lve task are stored in 
fields DBGEXTSL_RO through DBGEXTSL_PSL. 


OUTPUTS = The register set of the new active task 
modifi 


as 
ed by ene run-time system, in DBGEXT$L_RO 
through DBGEXTSL_PSL. 
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The DBGEXT$V_PSEUDO_GO flag may be set, in which case, 
DEBUG should perform a ‘‘pseudo go"’ operation. 


' 
i 
' 
DBGEXTSK_SET_ACTIVE = 9, 


SET_TERMINATE is used to cause ADA to terminate a task. it is used 
to implement the command SET TASK/TERMINATE. 


' 

i 

' 

: INPUTS - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
i f the TASK_VALUE field is zero and the ALL flag 

s set, then the function is done for all tasks. 

OUTPUT = none 

DBGEXTSK_SET_TERMINATE = 10, 


! SET_HOLD is used to put a task on hold or to release a task that was 
previous |y put on hold. It is used to implement the command 
ET TASK/HOLD which leaves the state of a task as-is, except that each 
task is marked HOLD. 


! 
! 
i 
' 
INPUTS - The task value is placed in the ®RGEXTSL_TASK_VALUE field. 
: 
i 


If the TASK_VALUE field is zero and the ALL flag 
is set, then the function is done for all tasks. 


BCC Will the /ALL selection criteria be used for the SET_xxx codes? -tbs))% 
i The desired status of HOLD is placed into the 
DBGEXTSV_HOLD field. (1 => HOLD, 0 => RELEASE) 


1RCCIs the request 1=>1 or 0=>0 legal? -tbs))% 


! OUTPUT = none 
DBGEXTSK_SET_HOLD = 11, 


: GET_PRIORITY inquires about the priority of a specified task. 

INPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
: OUTPUT - The priority is returned in the DBGEXTSW_PRIORITY field. 
DBGEXTSK_GET_PRIORITY = 12, 


SET_PRIORITY is used to set the priority of a specified task. 
INPUTS - The task value is placed in the DBGEXTSL_TASK_VALUE field. 


f the TASK_VALUE field is zero ang the ALL flag 
fr) ft) 


i 
i 
i 
i 
i 
s set, then the function is done for all tasks. 
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: OUTPUT 
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The desired priority is placed in the DBGEXTSW_PRIORITY field. 
= none. 


DBGEXTSK_SET_PRIORITY = 13, 


Qeecesesecesasasecace 


RESTORE PRIORITY is used to restore the priority of a task back 
to its normal value (as it would be without DEBUG intervention). 


INPUTS 


OUTPUT 


- The task value is placed in the DBGEXTSL_TASK_VALUE field. 


If the TASK_VALUE field is zero and the ALL flag 
is set, then the function is done for all tasks. 


= none. 


DBGEXTSK_RESTORE_PRIORITY = 14, 


GET_REGISTERS is used to obtain the register set of a task. 


' 

‘ 

: INPUT - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
i OUTPUTS - The register values are returned in the DBGEXTS$L_RO 
through DBGEXTSL_PSL fields. 

i NOTE: Only DEBUG knows the register set of the active task 

‘ en ly this call is invalid for the active task. 

A return status of STSSK_SEVERE is returned. 
DBGEXTSK_GET_REGISTERS = 15, 


+ i REGISTERS is used to change the register values of a 


i this"may be needed, for example, in SET TASK T;DEPOSIT RSs 3 66 


! 

' 

4 

: INPUTS - The task value is placed in the DBGEXTSL_TASK_VALUE field. 
i The register values are placed in the DBGEXTS$L_RO 

: through DBGEXTSL_PSL fields. 

: OUTPUT _— = _none. 

i NOTE: Only DEBUG knows the register set tof the active task 

: hence, this call is invalid for the active task. 

A return status of STS$K_SEVERE is returned. 
DBGEXTSK_SET_REGISTERS = 16, 

! ENABLE even NT is used during processing of a ‘SET BREAK/EVENT="" or 
“SET TRACE/EVENT="" command to enable resorting of a given kind of event. 
i INPUTS = The DBGEXTSL_EVENT_ID field contains a code identi tying 

i 


the event betng enabled. The possible values of t 
code are defined Colen. 
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The DBG — TASK_VALUE field contains a task vaiue further 
alify ne Fie event being enabled. This may be zero 
f the a L" flag is | 


For example, 

if we are enabling ' ‘task termination’ and we 144) 
task value, ~— we only want to break on termination of 
that task. If we enable ‘task termination’ events and 
set the Abt flag, we want to be notified of any 

task termination. 


OUTPUT = none 
DBGEXTSK ENABLE _EVENT = 17, 


' DISABLE_EVENT is seq during processing of a “CANCEL BREAK/EVENT="" or 
a oANceL TRACE/E VENT "command to disable reporting of a given kind of 
event. 

i 

i INPUTS - The DBGEXTSL EVENT_ID field contains a code identifying 

; the event being disabled. The possible values of this 

code are defined below. 

The DBGEXTSL_TASK_VALUE field contains a task value further 
; ualifying the evént being disabled. This may be zero 

f the "A L™ flag is Lit. 

OUTPUT - none 

D 


BGEXTSK_DISABLE_EVENT = 18, 


: A maximum task code is defined for CASE statement bounds. 
DBGEXTSK_MAX_FUNCT = 18; 


16 
13-60-1984 G3 ee ee etl et rag aie: Sac ibecext.reo:1 


760 + 

ri COMPLETION STATUS 

e6 The run time system has two means of providing a completion status <-- the 
ree return value of the function and the contents of DBGEXTSL_STATUS. 

106 Function Return Value -- 

76 


The run time system should, . ts first act » attempt to read and verify 


s its f ion 
the field DBGEXTSV_FACILITY_ID in DBGEXTSCONTROL_BLOCK. Ops ional ty. it may 
also PROBE the confrol block for read/writability. If the FACILITY_ID is 
correct, the run time system should eventually return: 
STSSK_SUCCESS = service successfully completed 
Otherwise, the run time system should immediately return: 
STSSK_SEVERE - service failed 


This helps to insure that an incorrect External Control Block will be 
detected before it is written to. 


SNS SIO 


SHUEARAN AS SAVOUR UN OOO 


Contents of DBGEXTSL_STATUS -=- 


ALL other status and error conditions will be placed in the STATUS field of 
the control block. The possible values of the STATUS field are a composite 
of sever tty level and message number. Only two severity values are used. 

v 


SSNS NSS SSS SSNS SS 


They are given by STS$V_SEVERITY: 
a STSSK_SUCCESS - service successfully completed 
a4 In this case the message number (STS$V_MSG_NO) is zero. 
a | STSS$K_ERROR - service failed 
re In this case the message number (STSS$V_MSG_NO) is one of the following: 
798 LITERAL : 
799 
800 


DBGEXTSK_FUNCTION_NOT_IMP = 0, 

: The function requested is not implemented by the facility. 
DBGEXTSK_TASK_NOT_EXIST = 1, 

! Task number cannot be translated to a task value because the task does 


! not exist. Or task value does not point to a currently existing task 
! (this cannot always be detected). 
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a9 DBGEXTSK_TASK_IS_ACTIVE = 2, 
ag i Returned on a SET_REGISTER or GET_REGISTER function for the active task. 
He ! The run time systém cannot access the registers of teh active task. 
15 DBGEXTSK_TASK_IS_NULL = 3; 
816 ; 
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8 ! Returned on a SET_ACTIVE function for the null task. 
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PRINT ROUTINE INTERFACE 


is given in 
Bl 


e DBGEXTSL_PRINT_ROUTINE field. 


ND 
DBGSPRINT_ROUTINE = .control_block C DBGSL_PRINT_ROUTINE J; 


DBGSPRINT_ROUTINE ( NEW_LINE 
STRING. TO_PRINT, 
FAO_ARG_1; 
FAO-ARG-2,... 
FAO-ARG_nS : NOVALUE 


NEW_LINE - this can have one of two values: 
0 = Place the given string in the output buffer. 


STRING_TO_PRINT 
- this is a pointer to a counted ascii string 

Eg: UPLIT (ZASCIC ‘Outout this text’) 

This may be zero if the ACTION_CODE is ‘'NEWLINE'’. 


There may be FAO arguments following the string. 
The string thus may contain embedded FAO commands 
such as ''AC', ‘!SL", an” *o on. 


RCCFIXUP = THIS EXTENSION IS NOT GOOD!! ©%5))% 


In addition, there will be a DEBUG-specific extension 
to FAO which can be used for s mbolizing addresses. 


This indicates that the corresponding FAO argument 
the string. 
FAO_ARG1 through FAO_ARGn = optional parameters for FAO arguments. 
Example: suppose FOO\L is located at address 200. Then: 


DBGSPRINT_ROUTINE (DBGEXTSK_NEWLINE, 
aa (ZASCIC ‘Task switch at location !SA'), 


This would output: 
"Task switch at location FOO\L" 


ee ee te ee ee ee ee ee 


VAX=11_BLi 
_$255$DUA2 


The por toyeny, Ser ieee how to use the DEBUG print routine whose address 


1 = If the given string is non-zero, first place it in the 
buffer. In all cases, output the buffer to the screen. 


There will be a new command Te for ‘symbolize address’. 
is an address. It's symbolization is to be embedded into 
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EVENT ID 


The following define the possible values of the DBGEXTSL_EVENT_ID field. 


[" -esaceiare 


These are the predefined events that we can break or trace on. 

LITERA 
DBGEXTSK_MIN_EVENT_CODE = 0, 
DBGEXTSK_ INVOKE _DEBUG = 0, ! Unconditional DEBUG invokation 
DBGEXTSK_TASK_ACTIVATION = 1, ' First transition of a task to RUNNING 
DBGE XT$K~ TASK” SUSPENSION = ¢ ! Transition from RUNNING to SUSPENDED 
DBGEXTSK_TASK_SWITCH_FROM = 3, ! Transition from RUNNING to some state 
DBGEXTSK_TASK_SWITCH-TO = 4, ! Transition from some state to RUNNING 
DBGEXTSK"TASK_TERMINATION = 5, ! Any kind of termination 
! Ada specific tasking codes: 
DBGEXTSK_ TASK_ABORT_TERM = 6, ! Termination by abort 
DBGEXTSK~ TASK_EXCEP_TERM o 7, ! Termination by unhandled exception 
DBGEXTSK_TASK_EXCEP_REND = 8, ! Exception prapeget ios ¢ out of rendezvous 
BOGE TSS TASK J ENTRY CALL = 9 ! Executing an entry cai 
DBGEXT$K~TASK-ACCEPT = 16, i! Executing an accept 
DBGEXTSK_ TASK” SELECT = 11, ! Executing a select 
DBGEXTSK_MAX_EVENT_CODE = 11; 
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EVENT CONTROL BLOCK 


The Event Control Block is the data structure that the ADA (or other) 
! facility passes to DEBUG when it signals that a given event has occured. 


! For example, if you do a SET BREAK/ADAEVENT=TASK_SWITCH_TO, then . 
when a task switch occurs, the ADA run-time system will pignal the special 
signal DBGS_EVENT. A pointer to an “Event Control Block’ is passed 
as the ‘FAO ereynent of DBGS_EVENT. iE -9- 
LIBSSIGNAL (DBGS_EVENT, 1, .EVENT CONTROL BLOCK). (Note that this 
condition cannot ereperty be an SS$ condition because they are not 
allowed to have FAO arguments other than PC and PSL 
(except for the hardware conditions). Hence, the facility DBG was chosen. 
This condition is a DEBUG-defined condition that anyone can 
signal. The FAO count of 1 is required so that the message conforms 
toa ogee format for a seseogs vector.) Through proper use of the 
SEVERITY field and the NOMESSAGE bit in the condition, the 
signalier can be assured that events will be 
reflected’’ by Traceback should DEBUG not be mapped 
into the image (for some reason). So there rea are no 
restrictions on when this condition can be signalled. 


The control block contains a code indicating the facility 

that has originated the event and another code to indicate what event 

a scomerat. It also contains message text to be output announcing 
e event. 


The following illustrates the Event Control Block: 


DBGEXTSL_EVNT_EVENT_ID 
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DBGEXTSL_EVNT_FLAGS ; 
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DBGEXTSL_EVNT_MESSAGE_TXT ; 
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DBGEXTSL_EVNT_ARG_COUNT 
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DBGEXTSA_EVNT_ARG_VECT ; 
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FIELD DBGEXTSEVNT_FIELDS = 
DBGEXTSL_EVNT_ FACILITY _1D 


DBGE XT$L~EVNT~EVENT 


DBGEXTSL_EVNT_MESSAGE_TXT 
DBGEXTSL-EVNT_ARG_COURT 
DRGEKTSA_EVNT_ARG_VECT 
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LITERAL 
DBGEXTSK_EVNT_BASE_SIZE = 5; 
CRO 
DBGEXTSEVENT CONTROL_BLOCK (NUM_ARGS) 
BLOCK CDBGEXTSK BASE SIZE = NUM_ ARGS ,LONG) 
FIELD (DBGEXTSEQNT_FIELDS)2; 


Explanation of fields: 


FACILITY_ID field: The code for te Cust DEF bi ee the 
event. If the CUST_DEF s set the 
event is a eae event’’. Otherwise, the 
only supported codes are ADA, PPA, and 
sca 


EVENT_ID field: This field contains the event code. | 
Event codes are numbered from 1 within 
each facility. Event code 0 is 
reserved in all facilities. It represents 
the unconditional event, that is, 
unconditional DEBUG entry. If the 
EVENT_ID field is zero, the REENTRY bit 
is checked. 


MESSAGE_TXT field: This is a@ pointer to a counted ascii got mo 
The string represents a message to be printed 
when the event occurs and is fomatted as an 

“fao control string The string may take FAO 
arguments. The str 4B may also contain the 
DEBUG extension to F 'SA', in order to 
symbolize an address. this extension is 
described above. NOTE: if this field is 0, 
it indicates that there is no message. 


ARG_COUNT field: Count of the number of FAO arguments that go 
with the text. 

ARG_VECT field: A vector of FAO arguments. 

MORE _TEXT flag: If this flag is TRUE, it indicates that DEBUG 


is to return control at the point of the signal 
gtter Stsoloxing to the qoenege. This is to be used 
for output of multi-line messages. (l.e., the 
run-time system should then resignal the event with 
Fee cout Line of message text in the MESSAGE_TXT 


REENTRY flag: If this flag is TRUE, then this event is a 
se hag | event that has occurred after a 
PSEUDO GO. EBUG is Sevens instructed 
to restore certain components of its state 
from the values shor 3 had at DEBUG's Last 
pacarsetten (e.g. AST enablement 
For this to be checked by DEBUG, the 
EVENT_ID tie dg MUST BE ZERO, thus indicating 
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REGISTERING EVENTS WITH DEBUG 


DEBUG's event handling feature is available to user he aga aS 
well as Digital software. DEBUG maintains an event table 
for each facility that chooses to register its events with DEBUG. 


Registering an event with DEBUG is very simple. The facility 
need only signal the following signal after DEBUG has 
been invoked in an image: 


LIBSSIGNAL (DBG$_REGISTER_EVENTS, 
rst_event_condition, 
second_event condition, 
etc. 


A List_of event conditions is chained below a master condition 
of DBGS_REGISTER_EVENTS. This signal may be raised as many 
times as desired to add more events to DEBUG's event table. 
Since DEBUG derives the facility number from the event 
condition, events for different facilities may be 

registered with the same signal. 


The event conditions appearing in the message vector must 
be defined in the facilities message file. The string 
defined in the message file is the string that DEBUG 

will use to name the event. 


For example, suppose we wish to add an event of PLIS_TASK_SWITCH. 
The following would do it: 


1. Add to PLI's message file: 
PLIS_FACILITY = xxx 
TASK_SWITCH “*TASK_SWITCH" 


2. Register the event with DEBUG 
LIBSSIGNAL (DBG$_REGISTER_EVENTS, PLIS_TASK_SWITCH) 


After the pogtecros tes any user can then type 
SET BREAK/EVENT=PLI$_TASK_SWITCH 


A command SET EVENT/FACILITY="PLI$_"* can be used so the facility 
refix can be omitted, e.g. SET BREAK/EVENT=TASK_SWITCH 
his will then not_be confused with an Ada task Switch. 
SET EVENT/NOFACILITY will eliminate the automatic prfixing of 
event names. 


To ginettty the registration of events by facilities, any 
facility should provide an entry point that users can | 
call from the DEBUGGER to load the events of that facility. 
To load PLI's events, then, a user would merely type 


DBG> CALL PLI$_LOAD_EVENTS 


‘e# Obviously, Ada's events should be registered with this same 
; general mechanism 
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COMMAND QUALIFIERS 
BLISS/LIBRARY=L1B$:DBGEXT.L32/LIST=LIS$:DBGEXT.LIS SRC$:DBGEXT.REQ 


Run Time: 706.5 
Elapsed Time: :09.6 
Lines/CPU Min: 962 
Lexemes/CPU-Min: 15106 
Memory Used: 38 pages 
Library Precompilation Complete 
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